Inside Macintosh: QuickDraw GX Objects /

Chapter 2 - Shape Objects / Shape Objects Reference

Functions / Creating and Manipulating Shape Objects

GXCopyToShape

The GXCopyToShape function copies the contents of one existing shape to another or else it creates a new shape and copies the contents of an existing shape to it. You can, for example, use this function to create a copy of a shape so that you can modify it without changing the original shape.

gxShape GXCopyToShape(gxShape target, gxShape source);

target

A reference to the shape to copy the source shape's contents into. If you specify nil for this parameter, the function creates a new shape.

source

A reference to the shape to copy from.

function result

A reference to the copy (that is, the target shape).

DESCRIPTION

The GXCopyToShape function copies the properties and the geometry of the shape specified by the source parameter into the shape specified by the target parameter. It also copies the references to the source shape's ink, style, transform, and tags; that is, after the function returns, the target shape and the source shape share the same ink, style, transform, and tag objects. This function increments by 1 the owner counts of the source shape's ink, style, transform, and tag objects, and disposes of the original ink, style, transform, and tags of the target shape.

If you specify nil for the target parameter, this function creates a new shape to copy the contents of the source shape into.

SPECIAL CONSIDERATIONS

If you specify nil for the target parameter and no error occurs, the GXCopyToShape function creates a new shape object; you are responsible for disposing of that object when you no longer need it.

If the target shape is locked, the GXCopyToShape function posts a shape_access_not_allowed error. If you try to copy a picture into a shape that is contained in the picture, this function posts a picture_cannot_contain_itself error. If you try to copy a shape of one type into the default shape of another type, this function posts a cannot_dispose_default_shape warning.

This function does not copy the pixel image of bitmap shapes, the shapes contained within picture shapes, or the set of style objects associated with glyph or layout shapes; instead, it copies the references to them. To obtain a complete copy of a bitmap shape, picture shape, glyph shape, or layout shape, use the GXCopyDeepToShape function.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
shape_access_not_allowed	(debugging version)
picture_cannot_contain_itself	(debugging version)
Warnings
cannot_dispose_default_shape	(debugging version)

SEE ALSO

To create a new shape that is a copy of the default shape instead of a copy of an existing shape, use the GXNewShape function, described on page 2-54.

The GXCopyDeepToShape function copies the pixel image of bitmap shapes and the shapes contained within picture shape; it is described in the next section. For more information about copying bitmap shapes and picture shapes, see Inside Macintosh: QuickDraw GX Graphics.

For information about copying typographic shapes, see the typographic shapes chapter of Inside Macintosh: QuickDraw GX Typography.